home *** CD-ROM | disk | FTP | other *** search
/ Turnbull China Bikeride / Turnbull China Bikeride - Disc 2.iso / STUTTGART / LANG / ADA / GNAT / !gcc / adainc / 6 / ads / s-taspri < prev    next >
Text File  |  1996-02-12  |  13KB  |  267 lines
  1. ------------------------------------------------------------------------------
  2. --                                                                          --
  3. --                 GNU ADA RUNTIME LIBRARY (GNARL) COMPONENTS               --
  4. --                                                                          --
  5. --                S Y S T E M . T A S K _ P R I M I T I V E S               --
  6. --                                                                          --
  7. --                                  S p e c                                 --
  8. --                           (Compiler Interface)                           --
  9. --                                                                          --
  10. --                             $Revision: 1.5 $                             --
  11. --                                                                          --
  12. --     Copyright (C) 1992,1993,1994,1995 Free Software Foundation, Inc.     --
  13. --                                                                          --
  14. -- GNARL is free software; you can  redistribute it  and/or modify it under --
  15. -- terms of the  GNU General Public License as published  by the Free Soft- --
  16. -- ware  Foundation;  either version 2,  or (at your option) any later ver- --
  17. -- sion. GNARL is distributed in the hope that it will be useful, but WITH- --
  18. -- OUT ANY WARRANTY;  without even the  implied warranty of MERCHANTABILITY --
  19. -- or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License --
  20. -- for  more details.  You should have  received  a copy of the GNU General --
  21. -- Public License  distributed with GNARL; see file COPYING.  If not, write --
  22. -- to  the Free Software Foundation,  59 Temple Place - Suite 330,  Boston, --
  23. -- MA 02111-1307, USA.                                                      --
  24. --                                                                          --
  25. -- As a special exception,  if other files  instantiate  generics from this --
  26. -- unit, or you link  this unit with other files  to produce an executable, --
  27. -- this  unit  does not  by itself cause  the resulting  executable  to  be --
  28. -- covered  by the  GNU  General  Public  License.  This exception does not --
  29. -- however invalidate  any other reasons why  the executable file  might be --
  30. -- covered by the  GNU Public License.                                      --
  31. --                                                                          --
  32. -- GNARL was developed by the GNARL team at Florida State University. It is --
  33. -- now maintained by Ada Core Technologies Inc. in cooperation with Florida --
  34. -- State University (http://www.gnat.com).                                  --
  35. --                                                                          --
  36. ------------------------------------------------------------------------------
  37.  
  38. --  This package provides low-level support for most tasking features.
  39. --  Not included is support for Clock, which is in package System.Task_Clock.
  40.  
  41. --  Note: this spec is not directly part of the compiler interface, but it
  42. --  is used by System.Tasking_Abortion, which is part of the interface.
  43.  
  44. --  This is a dummy version of this package (no tasking support).
  45.  
  46. with System.Task_Clock;
  47. --  Used for, Stimespec
  48.  
  49. with Unchecked_Conversion;
  50.  
  51. with System.Task_Info;
  52. package System.Task_Primitives is
  53.  
  54.    --  Low level Task size and state definition
  55.  
  56.    type LL_Task_Procedure_Access is access procedure (Arg : System.Address);
  57.  
  58.    type Pre_Call_State is new System.Address;
  59.  
  60.    type Task_Storage_Size is new Integer;
  61.  
  62.    type Machine_Exceptions is new Integer;
  63.  
  64.    type Error_Information is new Integer;
  65.  
  66.    type Lock is private;
  67.    type Condition_Variable is private;
  68.  
  69.    --  The above types should both be limited. They are not due to a hack in
  70.    --  ATCB allocation which allocates a block of the correct size and then
  71.    --  assigns an initialized ATCB to it. This won't work with limited types.
  72.    --  When allocation is done with new, these can become limited once again.
  73.    --  ???
  74.  
  75.    type Task_Control_Block is record
  76.       LL_Arg : System.Address;
  77.    end record;
  78.  
  79.    type TCB_Ptr is access all Task_Control_Block;
  80.  
  81.    --  Task ATCB related and variables.
  82.  
  83.    function Address_To_TCB_Ptr is new
  84.      Unchecked_Conversion (System.Address, TCB_Ptr);
  85.  
  86.    procedure Initialize_LL_Tasks (T : TCB_Ptr);
  87.    --  Initialize GNULLI. T points to the Task Control Block that should
  88.    --  be initialized for use by the environment task.
  89.  
  90.    function Self return TCB_Ptr;
  91.    --  Return a pointer to the Task Control Block of the calling task.
  92.  
  93.    procedure Initialize_Lock (Prio : System.Priority; L : in out Lock);
  94.    --  Initialize a lock object. Prio is the ceiling priority associated
  95.    --  with the lock.
  96.  
  97.    procedure Finalize_Lock (L : in out Lock);
  98.    --  Finalize a lock object, freeing any resources allocated by the
  99.    --  corresponding Initialize_Lock.
  100.  
  101.    procedure Write_Lock (L : in out Lock; Ceiling_Violation : out Boolean);
  102.    --  Lock a lock object for write access to a critical section. After
  103.    --  this operation returns, the calling task owns the lock, and
  104.    --  no other Write_Lock or Read_Lock operation on the same object will
  105.    --  return the owner executes an Unlock operation on the same object.
  106.  
  107.    procedure Read_Lock (L : in out Lock; Ceiling_Violation : out Boolean);
  108.    --  Lock a lock object for read access to a critical section. After
  109.    --  this operation returns, the calling task owns the lock, and
  110.    --  no other Write_Lock operation on the same object will return until
  111.    --  the owner(s) execute Unlock operation(s) on the same object.
  112.    --  A Read_Lock to an owned lock object may return while the lock is
  113.    --  still owned, though an implementation may also implement
  114.    --  Read_Lock to have the same semantics.
  115.  
  116.    procedure Unlock (L : in out Lock);
  117.    --  Unlock a locked lock object. The results are undefined if the
  118.    --  calling task does not own the lock. Lock/Unlock operations must
  119.    --  be nested, that is, the argument to Unlock must be the object
  120.    --  most recently locked.
  121.  
  122.    procedure Initialize_Cond (Cond : in out Condition_Variable);
  123.    --  Initialize a condition variable object.
  124.  
  125.    procedure Finalize_Cond (Cond : in out Condition_Variable);
  126.    --  Finalize a condition variable object, recovering any resources
  127.    --  allocated for it by Initialize_Cond.
  128.  
  129.    procedure Cond_Wait (Cond : in out Condition_Variable; L : in out Lock);
  130.    --  Wait on a condition variable. The mutex object L is unlocked
  131.    --  atomically, such that another task that is able to lock the mutex
  132.    --  can be assured that the wait has actually commenced, and that
  133.    --  a Cond_Signal operation will cause the waiting task to become
  134.    --  eligible for execution once again. Before Cond_Wait returns,
  135.    --  the waiting task will again lock the mutex. The waiting task may become
  136.    --  eligible for execution at any time, but will become eligible for
  137.    --  execution when a Cond_Signal operation is performed on the
  138.    --  same condition variable object. The effect of more than one
  139.    --  task waiting on the same condition variable is unspecified.
  140.  
  141.    procedure Cond_Timed_Wait
  142.      (Cond      : in out Condition_Variable;
  143.       L         : in out Lock; Abs_Time : System.Task_Clock.Stimespec;
  144.       Timed_Out : out Boolean);
  145.    --  Wait on a condition variable, as for Cond_Wait, above. In addition,
  146.    --  the waiting task will become eligible for execution again
  147.    --  when the absolute time specified by Timed_Out arrives.
  148.  
  149.    procedure Cond_Signal (Cond : in out Condition_Variable);
  150.    --  Wake up a task waiting on the condition variable object specified
  151.    --  by Cond, making it eligible for execution once again.
  152.  
  153.    procedure Set_Priority (T : TCB_Ptr; Prio : System.Priority);
  154.    --  Set the priority of the task specified by T to P.
  155.  
  156.    procedure Set_Own_Priority (Prio : System.Priority);
  157.    --  Set the priority of the calling task to P.
  158.  
  159.    function Get_Priority (T : TCB_Ptr) return System.Priority;
  160.    --  Return the priority of the task specified by T.
  161.  
  162.    function Get_Own_Priority return System.Priority;
  163.    --  Return the priority of the calling task.
  164.  
  165.    procedure Create_LL_Task
  166.      (Priority       : System.Priority;
  167.       Stack_Size     : Task_Storage_Size;
  168.       Task_Info      : System.Task_Info.Task_Info_Type;
  169.       LL_Entry_Point : LL_Task_Procedure_Access;
  170.       Arg            : System.Address;
  171.       T              : TCB_Ptr);
  172.    --  Create a new low-level task with priority Priority. A new thread
  173.    --  of control is created with a stack size of at least Stack_Size,
  174.    --  and the procedure LL_Entry_Point is called with the argument Arg
  175.    --  from this new thread of control. The Task Control Block pointed
  176.    --  to by T is initialized to refer to this new task.
  177.  
  178.    procedure Exit_LL_Task;
  179.    --  Exit a low-level task. The resources allocated for the task
  180.    --  by Create_LL_Task are recovered. The task no longer executes, and
  181.    --  the effects of further operations on task are unspecified.
  182.  
  183.    procedure Abort_Task (T : TCB_Ptr);
  184.    --  Abort the task specified by T (the target task). This causes
  185.    --  the target task to asynchronously execute the handler procedure
  186.    --  installed by the target task using Install_Abort_Handler. The
  187.    --  effect of this operation is unspecified if there is no abort
  188.    --  handler procedure for the target task.
  189.  
  190.    procedure Test_Abort;
  191.    --  ??? Obsolete?  This is intended to allow implementation of
  192.    --      abortion and ATC in the absence of an asynchronous Abort_Task,
  193.    --      but I think that we decided that GNARL can handle this on
  194.    --      its own by making sure that there is an Undefer_Abortion at
  195.    --      every abortion synchronization point.
  196.  
  197.    type Abort_Handler_Pointer is access procedure (Context : Pre_Call_State);
  198.  
  199.    procedure Install_Abort_Handler (Handler : Abort_Handler_Pointer);
  200.    --  Install an abort handler procedure. This procedure is called
  201.    --  asynchronously by the calling task whenever a call to Abort_Task
  202.    --  specifies the calling task as the target. If the abort handler
  203.    --  procedure is asynchronously executed during a GNULLI operation
  204.    --  and then calls some other GNULLI operation, the effect is unspecified.
  205.  
  206.    procedure Install_Error_Handler (Handler : System.Address);
  207.    --  Install an error handler for the calling task. The handler will
  208.    --  be called synchronously if an error is encountered during the
  209.    --  execution of the calling task.
  210.  
  211.    procedure LL_Assert (B : Boolean; M : String);
  212.    --  If B is False, print the string M to the console and halt the
  213.    --  program.
  214.  
  215.    Task_Wrapper_Frame : constant Integer := 72;
  216.    --  This is the size of the frame for the Pthread_Wrapper procedure.
  217.  
  218.    type Proc is access procedure (Addr : System.Address);
  219.  
  220.    --  Test and Set support
  221.  
  222.    type TAS_Cell is private;
  223.    --  On some systems we can not assume that an arbitrary memory location
  224.    --  can be used in an atomic test and set instruction (e.g. on some
  225.    --  multiprocessor machines, only memory regions are cache interlocked).
  226.    --  TAS_Cell is private to facilitate adaption to a variety of
  227.    --  implementations.
  228.  
  229.    procedure Initialize_TAS_Cell (Cell :    out TAS_Cell);
  230.    pragma Inline (Initialize_TAS_Cell);
  231.    --  Initialize a Test And Set Cell.  On some targets this will allocate
  232.    --  a system-level lock object from a special pool.  For most systems,
  233.    --  this is a nop.
  234.  
  235.    procedure Finalize_TAS_Cell (Cell : in out TAS_Cell);
  236.    pragma Inline (Finalize_TAS_Cell);
  237.    --  Finalize a Test and Set cell, freeing any resources allocated by the
  238.    --  corresponding Initialize_TAS_Cell.
  239.  
  240.    procedure Clear (Cell : in out TAS_Cell);
  241.    pragma Inline (Clear);
  242.    --  Set the state of the named TAS_Cell such that a subsequent call to
  243.    --  Is_Set will return False.  This operation must be atomic with
  244.    --  respect to the Is_Set and Test_And_Set operations for the same
  245.    --  cell.
  246.  
  247.    procedure Test_And_Set (Cell : in out TAS_Cell; Result : out Boolean);
  248.    pragma Inline (Test_And_Set);
  249.    --  Modify the state of the named TAS_Cell such that a subsequent call
  250.    --  to Is_Set will return True.  Result is set to True if Is_Set
  251.    --  was False prior to the call, False otherwise.  This operation must
  252.    --  be atomic with respect to the Clear and Is_Set operations for the
  253.    --  same cell.
  254.  
  255.    function  Is_Set (Cell : in TAS_Cell) return Boolean;
  256.    pragma Inline (Is_Set);
  257.    --  Returns the current value of the named TAS_Cell.  This operation
  258.    --  must be atomic with respect to the Clear and Test_And_Set operations
  259.    --  for the same cell.
  260.  
  261. private
  262.    type Lock is new Integer;
  263.    type Condition_Variable is new Integer;
  264.    type TAS_Cell is new Integer;
  265.  
  266. end System.Task_Primitives;
  267.